Description

In this example, TRIDENT document signature API is used to sign a PDF document. This operation is requested by a document signature portal (doc_sign) on behalf of a user (john.doe) who logs in to the portal after authenticating in TRIDENT by password. Signing the document entails four steps:

1. Obtaining the token for accessing the signature operations

2. Creating the document signature process

3. Executing the document signature process

4. Obtaining the signed document

Lastly, after the signature is performed, the document signature process used is deleted.

The portal was registered in TRIDENT (txeidas.safelayer.com) as an OAuth 2.0 client application, which means it has an identifier (docsign) and shares a secret with the platform (demodemo). Furthermore, the portal was associated to two authorization servers: one (main) for obtaining the access tokens for accessing the identity data of users; and the other (esignsp) for obtaining the access tokens for performing the signature operations in the documents.

During the signature process, TRIDENT obtains authorization implicitly from the user on two occasions:

• The first time so the signature services provider can obtain the user's signing identities: the reauthentication associated to this authorization does not require the user's intervention as it is performed with the same authentication flow used to log in to the portal and this flow establishes SSO for the password factor.

• The second time so the signature services provider can generate the signature on the document using one of the user's signing identities: the reauthentication associated to this authorization only requires user intervention if the signature is to be generated on a server because in this case the reauthentication is performed with a flow that, in addition to the password (which is not prompted for again because it has factor SSO), requires an OTP (which is always prompted for because it has no factor SSO). Furthermore, the associated reauthentication does not require the user's intervention if the signature must be generated with a mobile device as in this case the reauthentication is performed with the same authentication flow used to log in to the portal and this flow establishes SSO for the password factor.

The portal is indifferent to which signing identity is used for signing. The user chooses this identity from the signing identities presented to them by the TRIDENT after obtaining the corresponding authorization.

Obtaining the Token for Accessing the Signature Operations

Firstly, the document signature portal sends the following message to the TRIDENT to obtain the access token for accessing the PDF document signing operations (see the Obtain a Token operation):

Note that the portal must use its identifier and the secret it shares with the TRIDENT to authenticate using the HTTP basic authentication scheme (RFC 2617). Also note that the portal specifies that its authentication also proves having the right to obtain the access token requested (grant_type=client_credentials).

The access token is obtained in the following HTTP response:

Creating the Document Signature Process

The portal requests the creation of the PDF document signature process by sending the following message to the TRIDENT signature services provider (see the Create a Document Signature Process operation and note that, for the sake of readability, {pdfToBeSigned} replaces the binary content of the PDF document).

Note that, as well as providing the PDF document (document={pdfToBeSigned}), the portal also specifies the type of process that must be created to sign it (process_type=urn:safelayer:eidas:processes:document:sign:esigp). The portal demonstrates its authorization for requesting the signing of the document by including the access token (403e...e7b3) in the Authorization header. It uses the finished_callback_url property to specify the URL for notifying the finalizing of the signature process (returnurl=https://docsign.safelayer.com/signedPdf/callback).

In the above message you can see that:

• A PAdES-BES (signer.parameters.type = "pades-bes") signature is to be performed, and the SHA-256 hash algorithm (signer.parameters.default_digest_algorithm = "sha256") is to be used for calculating the digital signature.

• The signature is to have an appearance (parameters.signature_field.appearance) to be located on the last page of the document (signer.parameters.signature_field.location.page.number = "last").

• The signature appearance comprises text, namely the distinguished name of the signer and the date and time the signature was made (signer.parameters.signature_field.appearance.signature_details.details[0].type = "subject", signer.parameters.signature_field.appearance.signature_details.details[1].type = "location" and signer.parameters.signature_field.appearance.signature_details.details[2].type = "date").

• Madrid, Spain is indicated as the place where the signature was generated (signer.parameters.location = "Madrid, Spain").

• The end of the signature process must be notified by redirecting the browser to the URL https://docsign.safelayer.com/signedPdf/callback (signer.finish_callback_url = "https://docsign.safelayer.com/signedPdf/callback")

If the request is successfully processed, the TRIDENT creates the signature process for the document and responds to the document signature portal with the following HTTP message.

Where you can see that the TRIDENT communicates with the signature portal that successfully created signature process and that it must redirect the user's browser to https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/ui?signerProcessId=sp_c4eed0a1f478f72454803695d53c4c5 (tasks.pending.url) (tasks.pending.url) for this process to continue. It also communicates to the signature portal that to obtain the signed document it must access https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/documents/dc_9ee0990055818516249f28558e1b256b/content (i.e., the URL resulting from concatenating /content to the URL specified in documents[0].url).

Executing the Document Signature Process

Next, the portal orders that the signature process be executed via the browser. Specifically, the portal sends the following redirect message to the browser (see the Execute a Document Signature Process operation):

To which the browser reacts by sending the following HTTP request to the TRIDENT:

To attend this request, the TRIDENT's electronic signature services provider, having previously obtained the corresponding authorization from the user, accesses the user's signing identities and, if there are more than one, prompts the user to select the one they want to sign the document with. Next, after again obtaining the corresponding authorization from the user, it requests that the signature provider generate the signature on the document with the signing identity selected. Lastly, after receiving the document signature from the signature provider, the signature services provider inserts it in the PDF document and notifies the signature portal that the process has finished by sending the following redirect response to the browser (which sends the browser to the URL specified in the signer.finish_callback_url property of the request received to create the signature process):

To which the browser reacts by sending the following HTTP request to the document signature portal:

Obtaining the Signed Document

After receiving the above message, the signature portal sends the following message to the signature services provider of the TRIDENT to obtain the signed PDF document (see the obtaining a document operation):

Note that the portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header. Also note that the URL of the document requested is created by adding /content to the URL specified in the response received when the signature process for the document was created (the document[0].url property of the JSON object contained in the response).

Lastly, the portal receives the signed document in the following HTTP response message (note that, for the sake of readability, {pdfSigned} replaces the binary content of the signed PDF).

Deleting the Document Signature Process

After obtaining the signed PDF document, the document signature portal sends the following message to the TRIDENT's signature services provider to delete the document signature process used (see the Delete a Document Signature Process operation):

TRIDENT deletes the document signature process and responds with the following message: